Network Support Library

home *** CD-ROM | disk | FTP | other *** search

/ Network Support Library / RoseWare - Network Support Library.iso / btrieve / btr61m.exe / 09CH5A.TXT < prev next >

Wrap

Text File | 1993-07-16 | 30KB | 797 lines

CHAPTER 5 USING BTRIEVE UTILITIES This chapter provides the following sections: o "Btrieve Monitor Utility" - This utility monitors the activity of Btrieve. o "Btrieve Maintenance Utility"-This utility imports and exports Btrieve data and transfers data from one Btrieve file to another. o "Roll Forward Utility"-This utility recovers changes made to a Btrieve file between the time of the last backup and a system failure. Btrieve Monitor Utility The Btrieve Monitor utility (BTRMON.NLM) allows you to monitor Btrieve activities on a server. It provides information that is useful for both database administration and application programming diagnostics. NOTE: The information you receive from the Btrieve Monitor utility pertains only to the activity of the NLMs on the current server. The Btrieve Monitor utility runs as an NLM at the server. You can access it at the server console or through RCONSOLE at your workstation. System Requirements To run the Btrieve Monitor utility, be sure that the following software is loaded on your server: o NetWare v3.11 o Btrieve v6.1 or later o BSPXCOM, BSPXSTUB, or RSPXSTUB NOTE: Running Btrieve v6.1 in a NetWare v3.11 environment requires AFTER311.NLM, which Btrieve loads automatically. In addition, the following files must be located in the SYS:SYSTEM directory of the server: o BTRMON.NLM o BTRMON.HLP The NetWare INSTALL utility automatically places these files in the SYS:SYSTEM directory. Starting the Btrieve Monitor Utility To start the Btrieve Monitor utility, enter the following command at the server console prompt: LOAD BTRMON Alternatively, you can include the command line option /R with the LOAD command. The /R option specifies the update time for the statistics screens that the utility dynamically updates. The range of valid values for this option is from 500 to 60,000 milliseconds; the default value is 2,000 milliseconds. For example, if you want to start the Btrieve Monitor utility and instruct it to update the statistics screens every 3,500 milliseconds, enter the following command: LOAD BTRMON /R3500 Selecting Options from the Available Options Menu The Available Options menu is the first screen you see after starting the Btrieve Monitor utility: You can select one of the following options from the Available Options menu: o Active Resources - displays information about active Btrieve data files. o User Information - displays information about the users currently using the Btrieve NLM. This option also allows you to delete a user's SPX connection. o Resource Usage - shows current, peak, and maximum usage statistics for the Btrieve NLM. o Communication Statistics - displays Sequenced Packet Exchange (SPX) protocol statistics for the communications module you have loaded (BSPXCOM, BSPXSTUB, or RSPXSTUB). NOTE: When you are using the Btrieve Monitor utility, the statistics on the File Information, User Information, Resource Usage, and Communication Statistics screens are updated regularly. On the Active Btrieve Files and Active Btrieve Users screens, you must press the Insert key to see updated statistics. While running the Btrieve Monitor utility, you can return to the previous screen at any time by pressing the Esc key. To exit the utility, press Esc at the Available Options menu. When the Exit window appears, select Yes to verify that you want to exit. Monitoring Btrieve Files with the Active Resources Option You can use the Active Resources option on the Available Options menu to do the following: o List all active (open) files o Display additional information about a particular file o List all users accessing a particular file Listing Active Files To list all active Btrieve files, select Active Resources from the Available Options menu. The utility displays a scrollable list of active Btrieve files: The file pathnames appear in alphabetic order. To update the list of active Btrieve files, press Insert. Displaying Additional Information About an Active File For further information about a particular file, highlight the desired file listed in the Active Btrieve Files screen and press Enter. The utility displays a File Information screen similar to the following, providing information about the file you selected. Since the utility dynamically updates the statistics shown on this screen, you may notice the values changing as you view the screen. For a description of each field that appears on this screen, refer to Table 5-1. Table 5-1 lists, in alphabetic order, all fields associated with the Active Resources and User Information options. Listing Users Accessing a File From the Active Resources option╒s File Information screen, you can list all users accessing the designated file. Press Enter to display a scrollable list of active Btrieve users. (See Table 5-1 for a description of each field on this screen.) To update the list of active users, press Insert. Monitoring Btrieve Users with the User Information Option You can use the User Information option on the Available Options menu to do the following: o List all active Btrieve users o List the files that a specific user is accessing o Delete a user's SPX connection to Btrieve Listing All Users To list all Btrieve users active on the current server, select User Information from the Available Options menu. The Btrieve Monitor utility displays a scrollable list of active Btrieve users: The utility identifies each active user based on user location, as follows: o If the user is located at a workstation, the utility displays the username (such as JDOE). o If the user is located at a local server, the utility displays either the process-supplied, two-character agent ID or the full name of the process (such as NetWare SQL). o If the user is located at a remote server, the utility displays either the process-supplied, two-character agent ID or the full name of the process (such as NetWare SQL) provided the utility can determine the full name. To update the list of active users, press Insert. To display information about a user, highlight the user and press Enter. A User Information screen similar to the following appears. For a description of each field that appears on this screen, refer to Table 5-1. Since the utility dynamically updates the statistics shown on this screen, you may notice the values changing as you view the screen. Listing Files Accessed by a User While the User Information screen is displayed, you can press Enter to list all Btrieve files currently accessed by that user. A screen similar to the following appears. To update the list of active Btrieve files, press Insert. Deleting User Connections Deleting a user╒s connection removes the user from the list of active Btrieve users and terminates the user's SPX connection to Btrieve. Use the following steps to delete a user's SPX connection: 1. Select the User Information option on the Available Options menu. 2. On the Active Btrieve Users screen, highlight the user connection that you want to delete, and press the Delete key. If the Btrieve Monitor utility does not list a connection number for the user that you want to delete, a Btrieve session is still active, although the NetWare connection has been terminated. You must restart the workstation that originated the Btrieve session to delete the user for that session. To avoid this problem, ensure that your application issues a Btrieve Reset operation to close active Btrieve files and release all resources held by the application. 3. In the prompt box that appears, select Yes if you are sure you want to delete the specified user. Otherwise, select No or press Esc. Table 5-1 Active Resources and User Information Field Descriptions Field Description Cache Accesses Shows the number of times the user has made Btrieve calls that accessed the Btrieve cache buffers. Connection Number Displays the NetWare connection number of the process if the process originates at a workstation. If the process originates at a server, this column is empty. Disk Accesses Shows the number of times the user has made Btrieve calls that required disk I/O. Handles Shows the number of Btrieve handles the user has as a result of opening files. Btrieve creates a handle each time a user opens a file; therefore, a single user can have several handles for the same file. Locks Available Indicates the total number of read locks available to the user. Locks Used Indicates the number of locks that the user has explicitly requested. The number of locks in use varies, depending on whether the user is in a transaction, as follows: o If the user is outside a transaction, this number indicates the number of records that the user has explicitly locked. o If the user is inside a concurrent transaction, this number indicates the number of pages in the file that the user has explicitly locked. Although the user actually requests record locks, these are converted to page locks inside a concurrent transaction. Consequently, five record locks are shown as two page locks if the five records are stored on two pages. o If the user is inside an exclusive transaction or the user holds no locks, this number is zero. Open Mode Indicates the mode used to open the file: Accelerated - The application that opened the file has shared, read/write access. With Btrieve v6.x, Accelerated mode is equivalent to Normal mode unless the file is flagged transactional. Exclusive - The application that opened the file has exclusive access. Other applications cannot open the file until the calling application closes it. Normal - The application that opened the file has normal shared, read/write access. Read only - The application that opened the file has read-only access; the application cannot modify the file. Page Size Indicates the page size (in bytes) of this file. (A page is the smallest unit of storage that Btrieve moves between main memory and the disk.) Read-Only Flag Indicates whether the file is flagged through NetWare as read only. Record Locks Shows the lock status of the current record: s - Single-record lock outside a transactions S - Single-record lock within a transaction m - Multiple-record lock outside a transaction M - Multiple-record lock within a transaction N - No record locks Single-record locks allow a user to lock only one record at a time. Multiple-record locks allow a user to lock more than one record at a time. Records Deleted Number of records the user has deleted. Records Inserted Number of records the user has inserted. Records Read Number of records the user has read. Records Updated Number of records the user has updated. Site Specifies the location of the user process, as follows: LS - Local server RS - Remote server WS - Workstation Task Number Contains the process-supplied task number if the process originates at the server, a Windows workstation, or an OS/2 workstation. If the process originates at a DOS workstation, this column contains the SPX socket number. Transaction Lock Indicates whether the entire file is locked by a transaction. A transactional file lock exists only as long as the application that opened the file is processing a transaction. Y indicates the entire file is locked. N indicates the file is not locked. TTS Flag Indicates whether TTS is being used with the file. (For more information on TTS, refer to your NetWare documentation.) User Location Identifies the user process, as follows: u If the user is located at a workstation, this column contains the network number and node address. u If the user is located at the server, this column contains the server name. Monitoring Resources with the Resource Usage Option The Resource Usage option on the Available Options menu shows you (in real time) the total resources in use by the Btrieve NLM since it was loaded. When you select this option, the Btrieve Monitor utility displays the Btrieve Resource Usage screen. Since the utility dynamically updates the statistics shown on this screen, you may notice the totals changing as you view the screen. The Current values on the Btrieve Resource Usage screen are cumulative from the time you enter the screen. Table 5-2 shows the field descriptions for the Resource Usage screen in alphabetic order. Table 5-2 Resource Usage Field Descriptions Field Description Statistics Clients Number of Btrieve processes. Current Number of active Btrieve processes. A process can be a BSPXCOM thread representing a client, a Message Router thread representing a client, or a client NLM on the present server. Peak Highest number of processes simultaneously active since the Btrieve NLM was loaded. Maximum Value set for the Number of Remote Sessions configuration option. Files Number of active Btrieve files. Current Number of active Btrieve files. Peak Highest number of Btrieve files that have been open simultaneously since the Btrieve NLM was loaded. Maximum Value set for the Number of Open Files configuration option. Handles Number of handles issued for Btrieve files. Current Number of active file handles. Peak Highest number of handles used simultaneously since the Btrieve NLM was loaded. Maximum Value set for the Number of Handles configuration option. Locks Number of implicit (system) page locks involved in concurrent transactions. Current Number of implicit active page locks. Peak Highest number of implicit page locks used simultaneously since the Btrieve NLM was loaded. Maximum Maximum simultaneous page locks that the system will allow. Threads Number of programs or program threads calling Btrieve simultaneously. Current Last system snapshot of active programs or program threads calling Btrieve simultaneously. Peak Maximum value ever encountered for the Current value since the NLM was loaded. Transactions Number of concurrent and exclusive transactions. Current Number of active concurrent and exclusive transactions. Peak Highest number of transactions active simultaneously since the Btrieve NLM was loaded. Maximum Value set for the Number of Transactions configuration option. Monitoring SPX Activity with the Communication Statistics Option The Communication Statistics option on the Available Options menu shows you (in real time) the network requests, packet buffers, and sessions in use for the communications module you have loaded. When you select this option, the Btrieve Monitor utility displays the Communications Statistics screen for BSPXCOM, BSPXSTUB, or RSPXSTUB. The communication activity shown on this screen reflects the communication activity of the communications module loaded at your server: o If you loaded BSPXCOM, you see incoming and outgoing SPX statistics. o If you loaded BSPXSTUB, you see all zeros for the communication statistics. o If you loaded RSPXSTUB, you see incoming and outgoing SPX communication statistics from the Message Router. This screen does not show the communication activity of any remote NLMs. NOTE: The Total values shown on this screen are cumulative from the time Btrieve is loaded. The Current values are cumulative from the time you display the screen. Table 5-3 shows field descriptions for the Communication Statistics option, in alphabetic order. Table 5-3 Communication Statistics Field Descriptions Field Description Statistics Btrieve Requests Number of network requests the NLM has processed from workstations or remote server-based applications. Current Current value since the last screen update. Total The number of requests received since the Btrieve NLM was loaded. Concurrent Processes Number of remote requests the NLM processes at one time. Current Current value since the last screen update. Max The maximum number of remote clients the Btrieve NLM can process at one time. SPX Packet Buffers Number of SPX packet buffers available to the NLM. Available Current number of available packet buffers (as of the last screen update). Max Value set for the maximum number of available packet buffers. Each session is allocated two packet buffers for Btrieve requests. SPX Packets Received Number of SPX packets the NLM has received from applications. Current Current value since the last screen update. Total The number of packets received since the communications NLM was loaded. SPX Packets Sent Number of SPX packets the NLM has sent to other applications. Current Current value since the last screen update. Total The number of packets sent since the communications NLM was loaded. The total packets sent may be larger than the total packets received because a single request received might produce several packets sent. SPX Requests Processed Number of SPX requests the NLM has processed. Current Current value since the last screen update. Total The number of requests processed since the communications NLM was loaded. SPX Sessions Number of remote clients who have established SPX sessions with the communications NLM. Current Current value since the communications NLM was loaded. Max Value set for the Number of Remote Sessions configuration option. Peak Highest value since the communications NLM was loaded. This value indicates the highest number of SPX clients that have simultaneously had concurrent active sessions with the communications NLM. Unprocessed SPX Packets Number of SPX packets the NLM has received but not yet processed. Current Current value since the last screen update. Btrieve Maintenance Utility The Btrieve Maintenance utility (BUTIL.NLM) is a command line utility that allows you to create, manipulate, and recover Btrieve data files. It runs as an NLM at the server. You can access it at the server console or at a workstation through the RCONSOLE utility. You can execute the Maintenance utility commands from the server command line or from a command file. To run the Maintenance utility, be sure that the following are installed on your server: o NetWare v3.11 o Btrieve v6.1 or later NOTE: Running Btrieve v6.1 in a NetWare v3.11 environment requires AFTER311.NLM, which Btrieve loads automatically. Utility Overview This section provides information you need to know before using the Maintenance utility commands. It discusses the required command format, the concepts you should understand before running the Maintenance utility, and the use of command files. NOTE: If you have used the utility before, you may want to skip to the individual command discussions., (The commands are discussed in alphabetic order.) Command Format The format for the Maintenance utility commands is as follows: LOAD BUTIL [-command [parameter ...]] | @commandFile -command A Maintenance utility command, such as COPY. You must precede the command with a dash (-), commandFile Full pathname of a command file. Table 5-4 Maintenance Utility Commands Command Description CLONE Creates a new, empty Btrieve file using an existing file's specifications. CLROWNER Clears the owner name of a Btrieve file. COPY Copies the contents of one Btrieve file to another. CREATE Creates a Btrieve file. DROP Drops an index. ENDBU Ends continuous operation on Btrieve files defined for backup. INDEX Creates an external index file. LOAD Loads the contents of a sequential file into a Btrieve file. RECOVER Reads data sequentially from a Btrieve file and writes the results to a sequential file. SALVAGE Examines a file╒s Page Allocation Table (PAT) to determine if corruption has occurred and if repair is required. SAVE Reads data along a key path and writes the results to a sequential file. SETOWNER Assigns an owner name to a Btrieve file. SINDEX Creates an index. STARTBU Starts continuous operation on files defined for backup. STAT Reports statistics about file attributes and current sizes of Btrieve files. VER Displays the version of the Btrieve NLM that is loaded at the server.